package io.gitee.luoyuan800.tool.llm.agent;

import io.gitee.luoyuan800.tool.llm.bean.Message;

import java.util.stream.Stream;

/**
 * AI 智能体接口，定义与 AI 进行交互的各种聊天方式。
 * <p>
 * 该接口提供了多种与 AI 对话的方法，包括普通聊天、带思考过程的聊天、
 * 图片识别聊天以及流式聊天等。
 * </p>
 *
 * @author Luoyuan/Gavin
 */
public interface AiAgent {
    /**
     * 与 AI 进行简单的文本对话。
     *
     * @param msg 用户输入的聊天消息
     * @return AI 返回的响应消息
     */
    String chat(String msg);

    /**
     * 与 AI 进行文本对话，可选择是否显示思考过程。
     *
     * @param msg 用户输入的聊天消息
     * @param showThink 是否显示 AI 的思考过程
     * @return AI 返回的响应消息
     */
    String chat(String msg, boolean showThink);

    /**
     * 发送包含图片的消息与 AI 进行对话，并可选择是否启用思考过程。
     *
     * @param msg 用户输入的文本消息
     * @param image 图片的 URL 或 base64 编码数据
     * @param enableThinking 是否启用 AI 的思考过程
     * @return AI 返回的响应消息
     */
    String chatWithImage(String msg, String image, boolean enableThinking);

    /**
     * 发送包含图片的消息与 AI 进行简单对话（默认不显示思考过程）。
     *
     * @param msg 用户输入的文本消息
     * @param image 图片的 URL 或 base64 编码数据
     * @return AI 返回的响应消息
     */
    String chatWithImage(String msg, String image);

    /**
     * 与 AI 进行流式文本对话，返回消息流。
     * <p>
     * 适用于需要实时获取 AI 响应结果的场景。
     * </p>
     *
     * @param msg 用户输入的聊天消息
     * @return 包含 AI 响应消息的流 ({@link Stream})
     */
    Stream<Message> streamChat(String msg);
}
